<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Python Tutorial for Robot Framework Test Library Developers</title>
<style type="text/css">

/* Robot Framework User Guide Style Sheet

   This stylesheet contains styles from restructuredText's default 
   'html4css1.css' and after that modifications needed for Robot Framework User
   Guide. These styles are added into the same file against suggestions at 
   reST's stylesheet HowTo mentioned below, because we want to be able to
   embed all styles into the created HTML file. Everything before 'Robot 
   Framework User Guide Modifications' text is from 'html4css1.css' without 
   any changes so that part can still be changed easily.
*/


/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }


/* **************************************** *
 * Robot Framework User Guide Modifications * 
 * **************************************** */

/* Tables
   - example, tsv-example: test data examples
   - messages: log message examples
   - tabular: normal tabular information
*/
table.example, table.tsv-example, table.messages, table.tabular {
    border: 1px solid #808080;
    border-collapse: collapse;
    empty-cell: show;
    margin: 0.5em 2em;
}
table.example caption, table.tsv-example caption, table.tabular caption {
    text-align: left;
    padding-bottom: 0.5em;
    font-style: italic;
    font-size: 0.9em;
    width: 100%;
}
table.example th, table.example td, table.tsv-example td {
    border: 1px solid #808080;
    font-family: arial,helvetica,sans-serif;
    height: 1.2em;
    font-size: 0.8em;
}
table.example th {
    padding: 0.1em 1em;
    background: #E0E0E0;
}
table.example td, table.tsv-example td {
    padding: 0.1em 1em 0.1em 0.3em;
}
table.tabular th, table.tabular td {
    border: 1px solid black;
    padding: 0.1em 0.3em;
    height: 1.2em;
    font-size: 0.8em;
}
table.messages {
    border: 1px solid gray;
    font-family: monospace;
    margin: 1em 2em;
    width: 60%;
}
table.messages td {
    vertical-align: top;
    padding: 0.1em 0.2em;
}
table.messages td.time {
    width: 7em;
    letter-spacing: -0.05em;
} 
table.messages td.level {
    width: 5em;
    text-align: center;
}
table.messages td.fail, table.messages td.error {
    color: red;
}
table.messages td.pass {
    color: #009900;
}
table.messages td.warn {
    color: #FFCC00;
}

/* Roles -- these are defined in roles.txt file */

.var {
    background: #f4f4f4;
    font-size: 0.9em;
}
.opt {
    font-style: italic;
}
.prog, .code, .cli {
    background: #f4f4f4;
    font-family: monospace;
}
.msg {
    font-family: monospace;
}
.name {  
    font-style: italic;
}
.path {
    font-style: italic;
}
.misc, .literal {
    background: #f4f4f4;
}


/* Overridden and modified styles */

cite {
    font-size: 0.95em;
}
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
    border: 1px solid gray;
    margin: 1em 2em;
    padding: 0.7em 1em;
    font-size: 0.9em;
}
pre.literal-block, pre.doctest-block {
    background: #f4f4f4;
}
li, li p.first {
    margin-top: 0.3em;
    margin-bottom: 0.3em;
}
div.contents li {
    margin-top: 0em;
    margin-bottom: 0em;
}
a img {
    border: 1px solid blue;
}

/* Pygments 

- Styles generated using "HtmlFormatter().get_style_defs('.highlight')"
- Changed only background (f8f8f8 -> f4f4f4) and added margin
- For more details see e.g. http://pygments.org/docs/quickstart/
*/

.highlight  { background: #f4f4f4; margin: 1em 2em; }
.highlight .c { color: #408080; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #808080 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #7D9029 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

</style>
</head>
<body>
<div class="document" id="python-tutorial-for-robot-framework-test-library-developers">
<h1 class="title">Python Tutorial for Robot Framework Test Library Developers</h1>

<!-- This data file has been placed in the public domain. -->
<!-- Derived from the Unicode character mappings available from
<http://www.w3.org/2003/entities/xml/>.
Processed by unicode2rstsubs.py, part of Docutils:
<http://docutils.sourceforge.net>. -->
<!-- Roles to use in text like :rolename:`text`. Styled in userguide.css.
- var    variables
- opt    settings in setting table (e.g. Force Tags), tc/kw tables
         (e.g [Documentation]) and command line options (e.g. - -name)
- prog   program names (e.g. rebot, risto.py)
- code   programming code
- msg    test case status and message, as well as log messages and levels
- name   keyword, library, test case, test suite, etc. names
- cli    command line examples (note that options alone use opt)
- path   file names and paths
- misc   everything else (synonym to ``text``) -->
<div class="line-block">
<div class="line">Copyright © Nokia Siemens Networks 2008-2012</div>
<div class="line">Licensed under the <a class="reference external" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported</a> license</div>
</div>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id8">Introduction</a></li>
<li><a class="reference internal" href="#getting-started" id="id9">Getting started</a><ul>
<li><a class="reference internal" href="#installation" id="id10">Installation</a></li>
<li><a class="reference internal" href="#interactive-interpreter" id="id11">Interactive interpreter</a></li>
<li><a class="reference internal" href="#python-editors" id="id12">Python editors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#variables" id="id13">Variables</a><ul>
<li><a class="reference internal" href="#basic-data-types" id="id14">Basic data types</a></li>
<li><a class="reference internal" href="#declaring-variables" id="id15">Declaring variables</a></li>
</ul>
</li>
<li><a class="reference internal" href="#first-program" id="id16">First program</a></li>
<li><a class="reference internal" href="#functions" id="id17">Functions</a><ul>
<li><a class="reference internal" href="#creating-functions" id="id18">Creating functions</a></li>
<li><a class="reference internal" href="#optional-and-named-arguments" id="id19">Optional and named arguments</a></li>
<li><a class="reference internal" href="#variable-number-of-arguments" id="id20">Variable number of arguments</a></li>
<li><a class="reference internal" href="#returning-values" id="id21">Returning values</a></li>
<li><a class="reference internal" href="#documenting-functions" id="id22">Documenting functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#container-data-types" id="id23">Container data types</a><ul>
<li><a class="reference internal" href="#lists" id="id24">Lists</a></li>
<li><a class="reference internal" href="#tuples" id="id25">Tuples</a></li>
<li><a class="reference internal" href="#dictionaries" id="id26">Dictionaries</a></li>
</ul>
</li>
<li><a class="reference internal" href="#control-flow" id="id27">Control Flow</a><ul>
<li><a class="reference internal" href="#conditional-execution" id="id28">Conditional execution</a></li>
<li><a class="reference internal" href="#looping" id="id29">Looping</a></li>
<li><a class="reference internal" href="#list-comprehensions" id="id30">List comprehensions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#modules" id="id31">Modules</a><ul>
<li><a class="reference internal" href="#importing-modules" id="id32">Importing modules</a></li>
<li><a class="reference internal" href="#creating-modules" id="id33">Creating modules</a></li>
<li><a class="reference internal" href="#module-search-path-pythonpath" id="id34">Module search path (PYTHONPATH)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#advanced-features" id="id35">Advanced features</a><ul>
<li><a class="reference internal" href="#classes-and-instances" id="id36">Classes and instances</a></li>
<li><a class="reference internal" href="#exceptions" id="id37">Exceptions</a></li>
<li><a class="reference internal" href="#regular-expressions" id="id38">Regular expressions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#unit-testing" id="id39">Unit testing</a></li>
<li><a class="reference internal" href="#writing-test-libraries" id="id40">Writing test libraries</a><ul>
<li><a class="reference internal" href="#library-api-basics" id="id41">Library API basics</a></li>
<li><a class="reference internal" href="#executable-example" id="id42">Executable example</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id8">Introduction</a></h1>
<ul class="simple">
<li>This is self learning material to learn how to program using <a class="reference external" href="http://python.org">Python
language</a>. The target is to learn enough Python to be able to start
creating test libraries for <a class="reference external" href="http://robotframework.org">Robot Framework</a>.</li>
<li>Earlier programming experience is expected but not absolutely
necessary.</li>
<li>The main study material for this training is the excellent <em>Dive Into
Python</em> book which is freely available for on-line reading,
downloading or printing from <a class="reference external" href="http://diveintopython.net">http://diveintopython.net</a>.  It is
targeted for people who already know how to program but do not know
Python before.</li>
<li>If you are a novice programmer, it might better to start with <a class="reference external" href="http://www.greenteapress.com/thinkpython/thinkpython.html">Think
Python</a> book. It is also available for free and its target audience
is people without any earlier programming knowledge.</li>
<li><a class="reference external" href="http://docs.python.org/tutorial">Python Tutorial</a>, available at <a class="reference external" href="http://python.org">http://python.org</a> and included in
the standard Python installation at least on Windows, is also very
good. Some of the sections in this training refer to it instead of
or in addition to Dive Into Python.</li>
<li>Python coding style guidelines are specified in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP-8</a>. Notice that
the Dive Into Python book uses <span class="code">camelCaseStyle</span> instead of the
recommended <span class="code">underline_style</span>.</li>
<li>Another highly recommended style guide, covering many essential
Python idioms and techniques, is <em>Code Like a Pythonista:
Idiomatic Python</em> available at
<a class="reference external" href="http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html">http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html</a></li>
<li>The official Python website at <a class="reference external" href="http://python.org">http://python.org</a> is a good place to
find more documentation and Python related information in
general.</li>
<li>If you need information about Jython, the Java implementation of
Python, you can start from <a class="reference external" href="http://jython.org">http://jython.org</a>.</li>
<li><em>The Definitive Guide to Jython</em> covers Jython in detail and is
useful especially if you are interested about Jython-Java
integration. It is freely available at <a class="reference external" href="http://jythonbook.com">http://jythonbook.com</a>.</li>
</ul>
</div>
<div class="section" id="getting-started">
<h1><a class="toc-backref" href="#id9">Getting started</a></h1>
<div class="section" id="installation">
<h2><a class="toc-backref" href="#id10">Installation</a></h2>
<ul class="simple">
<li>Most Linux distributions, OS X, and other UNIX like machines have
Python installed by default, but on Windows you probably need to
install it separately. Installers for different platforms can be
found from <a class="reference external" href="http://python.org">http://python.org</a>.</li>
<li>Robot Framework does not yet support Python 3.x versions and this
tutorial is also based on Python 2.x. Any 2.x version up from 2.3 is
sufficient but the latter versions are recommended.</li>
<li>It is highly recommended that you configure your system so that you
can run Python from command line simply by typing <span class="cli">python</span> and pressing
enter.<ul>
<li>On Windows, and possibly on some other systems, this requires
adding Python installation directory into <span class="var">PATH</span> environment
variable. For example <a class="reference external" href="http://code.google.com/p/robotframework/wiki/UserGuide">Robot Framework User Guide</a> has
instructions on how to do it in its <em>Installation</em> section.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="interactive-interpreter">
<h2><a class="toc-backref" href="#id11">Interactive interpreter</a></h2>
<ul>
<li><p class="first">Open the command prompt and type <span class="cli">python</span>. On Windows you can
also start the interpreter by selecting <tt class="docutils literal">Start &gt; All Programs &gt;
Python 2.x</tt>.</p>
</li>
<li><p class="first">Statements and expressions can be written in the interpreter.
Pressing enter will interpret the line and possible results are
echoed. Try for example:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="mi">1</span> <span class="o">+</span> <span class="mi">2</span>
<span class="go">3</span>
</pre></div>
</li>
<li><p class="first">Use <span class="cli">Ctrl-D</span> to exit on UNIX like machines and <span class="cli">Ctrl-Z</span>
and enter on Windows.</p>
<ul class="simple">
<li>With Python 2.5 and newer you can exit the interpreter also with
command <span class="code">exit()</span>.</li>
</ul>
</li>
<li><p class="first">Dive Into Python has some more examples:
<a class="reference external" href="http://diveintopython.net/installing_python/shell.html">http://diveintopython.net/installing_python/shell.html</a></p>
</li>
</ul>
</div>
<div class="section" id="python-editors">
<h2><a class="toc-backref" href="#id12">Python editors</a></h2>
<ul class="simple">
<li>Most general purpose text editors (Emacs, VIM, UltraEdit, ...) and
IDEs (Eclipse, Netbeans, ...) can be used to edit Python. There are
also some editors specially for Python.</li>
<li>The most important editor features are source highlighting and
handling indentation. Make sure your editor of choice supports them
either natively or via Python plugin or mode.</li>
<li>If you do not know any editor, you can at least get started with
<a class="reference external" href="http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/">IDLE</a>.  It is included in the standard Python installation on
Windows and can be installed also on other systems.</li>
</ul>
</div>
</div>
<div class="section" id="variables">
<h1><a class="toc-backref" href="#id13">Variables</a></h1>
<div class="section" id="basic-data-types">
<h2><a class="toc-backref" href="#id14">Basic data types</a></h2>
<ul>
<li><p class="first">Python has strings, integers, floating point numbers, Boolean values
(<span class="code">True</span> and <span class="code">False</span>) similarly as most other programming
languages.</p>
</li>
<li><p class="first">Strings can be enclosed into double or single quotes. Different
quotest do not have any difference like they do for example in Perl.</p>
</li>
<li><p class="first">Unicode strings have a special syntax like <span class="code">u&quot;Hyv\xE4\xE4
y\xF6\t\xE4!&quot;</span>. Using Unicode with Python is not covered otherwise
in this tutorial.</p>
</li>
<li><p class="first"><span class="code">None</span> is a special value meaning nothing similarly as
<span class="code">null</span> in Java.</p>
</li>
<li><p class="first">Try at least these on the interpreter:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="mi">2</span> <span class="o">*</span> <span class="mf">2.5</span>
<span class="go">5.0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="s">&#39;This is easy&#39;</span>
<span class="go">&#39;This is easy&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="s">&quot;Ain&#39;t it&quot;</span>
<span class="go">&quot;Ain&#39;t it&quot;</span>
</pre></div>
</li>
</ul>
</div>
<div class="section" id="declaring-variables">
<h2><a class="toc-backref" href="#id15">Declaring variables</a></h2>
<ul>
<li><p class="first">All different values can be assigned to variables. Valid characters
in variable identifiers are letters, underscore, and numbers,
although numbers cannot start the variable name.</p>
</li>
<li><p class="first">A variable needs not to be declared, it starts to exist when a value is
assigned for the first time.</p>
</li>
<li><p class="first">There is no need to specify the variable type either as the type is
got from the assigned variable automatically.</p>
</li>
<li><p class="first">Try it out:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="mi">3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span>
<span class="go">3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="mi">4</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">*</span><span class="n">b</span>
<span class="go">12</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">greeting</span> <span class="o">=</span> <span class="s">&#39;Hello&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">greeting</span>
<span class="go">&#39;Hello&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">greeting</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
<span class="go">&#39;HELLO&#39;</span>
</pre></div>
</li>
<li><p class="first">It is even possible to assign multiple variables at once:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="s">&#39;first&#39;</span><span class="p">,</span> <span class="s">&#39;second&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">&#39;first&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span>
<span class="go">&#39;second&#39;</span>
</pre></div>
</li>
</ul>
</div>
</div>
<div class="section" id="first-program">
<h1><a class="toc-backref" href="#id16">First program</a></h1>
<ul>
<li><p class="first">Create a file <span class="path">hello.py</span> with your editor of choice and write
this content into it:</p>
<div class="highlight"><pre><span class="k">print</span> <span class="s">&quot;Hello, world!&quot;</span>
</pre></div>
</li>
<li><p class="first">Then execute the file on the console like this:</p>
<div class="highlight"><pre><span class="go">python hello.py</span>
</pre></div>
</li>
<li><p class="first">As a result you should get <span class="code">Hello, world!</span> printed into the
screen. With Robot Framework keywords such messages would end up
into the log file.</p>
</li>
<li><p class="first">For more interesting examples see Dive Into Python:
<a class="reference external" href="http://diveintopython.net/getting_to_know_python/index.html">http://diveintopython.net/getting_to_know_python/index.html</a></p>
</li>
</ul>
</div>
<div class="section" id="functions">
<h1><a class="toc-backref" href="#id17">Functions</a></h1>
<div class="section" id="creating-functions">
<h2><a class="toc-backref" href="#id18">Creating functions</a></h2>
<ul>
<li><p class="first">Creating functions in Python is super easy. This example uses the
interpreter, but you can also write the code into the previous
<span class="path">hello.py</span> file and execute it.</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">hello</span><span class="p">():</span>
<span class="gp">... </span>    <span class="k">print</span> <span class="s">&quot;Hello, world!&quot;</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hello</span><span class="p">()</span>
<span class="go">Hello, world!</span>
</pre></div>
</li>
<li><p class="first">Note that in Python code blocks must be indented (four spaces is the
norm and highly recommended) and you close the block simply by
returning to the earlier indentation level. Inside a block you must
use the indentation level consistently.</p>
</li>
<li><p class="first">Notice also that this <span class="code">hello</span> function is actually already a
valid keyword for Robot Framework!</p>
</li>
<li><p class="first">A function with arguments is not that more complicated:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">print</span> <span class="s">&quot;Hello, </span><span class="si">%s</span><span class="s">!&quot;</span> <span class="o">%</span> <span class="n">name</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hello</span><span class="p">(</span><span class="s">&quot;Python&quot;</span><span class="p">)</span>
<span class="go">Hello, Python!</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hello</span><span class="p">(</span><span class="s">&quot;Robot Framework&quot;</span><span class="p">)</span>
<span class="go">Hello, Robot Framework!</span>
</pre></div>
</li>
<li><p class="first">The hard part in this example is string formatting (i.e. <span class="code">&quot;Hello,
%s!&quot; % name</span>) which uses similar syntax as for example C language.
More information about it can be found e.g. from Dive Into Python:
<a class="reference external" href="http://diveintopython.net/native_data_types/formatting_strings.html">http://diveintopython.net/native_data_types/formatting_strings.html</a></p>
</li>
</ul>
</div>
<div class="section" id="optional-and-named-arguments">
<h2><a class="toc-backref" href="#id19">Optional and named arguments</a></h2>
<ul>
<li><p class="first">Functions can have default values for some or all of its arguments:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;World&quot;</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">print</span> <span class="s">&quot;Hello, </span><span class="si">%s</span><span class="s">!&quot;</span> <span class="o">%</span> <span class="n">name</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hello</span><span class="p">()</span>
<span class="go">Hello, World!</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">hello</span><span class="p">(</span><span class="s">&quot;Robot&quot;</span><span class="p">)</span>
<span class="go">Hello, Robot!</span>
</pre></div>
</li>
<li><p class="first">If there are several optional arguments, it is also possible to
specify only some of them by giving their name along with the value
as the example below illustrates. Those arguments that do not have
default values cannot be omitted.</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>
<span class="gp">... </span>  <span class="k">print</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">d</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">0 1 2 3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="go">0 42 2 3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
<span class="go">1 1 10 3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span>
<span class="go">2 1 100 200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">(</span><span class="n">b</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n-Identifier">&lt;module&gt;</span>
<span class="nc">TypeError</span>: <span class="n-Identifier">test() takes at least 1 non-keyword argument (0 given)</span>
</pre></div>
</li>
<li><p class="first">Robot Framework keywords can have default values but they are always
used with positional arguments. For example, if the above <span class="code">hello</span>
method was used as a keyword, it could be used with zero or one
argument, and <span class="code">test</span> could be used with one to four arguments.</p>
</li>
<li><p class="first">Dive Into Python explains both optional and named arguments very well:
<a class="reference external" href="http://diveintopython.net/power_of_introspection/optional_arguments.html">http://diveintopython.net/power_of_introspection/optional_arguments.html</a></p>
</li>
</ul>
</div>
<div class="section" id="variable-number-of-arguments">
<h2><a class="toc-backref" href="#id20">Variable number of arguments</a></h2>
<ul class="simple">
<li>Function can also be created so that they take any number of
arguments. This is done by prefixing an argument after required and
optional arguments with an asterisk like <span class="code">*args</span>, and it means that
the specified argument gets all the &quot;extra&quot; arguments as a <a class="reference internal" href="#tuples">tuple</a>.</li>
</ul>
<blockquote>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">example</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">,</span> <span class="o">*</span><span class="n">rest</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">print</span> <span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">,</span> <span class="n">rest</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">1 2 ()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
<span class="go">1 2 (3,)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="go">1 2 (3, 4, 5)</span>
</pre></div>
</blockquote>
<ul class="simple">
<li>Using variable number of arguments works also with Robot Framework
keywords.</li>
<li>Python tutorial explains everything in this and the prvious section
in detail:
<a class="reference external" href="http://docs.python.org/tutorial/controlflow.html#more-on-defining-functions">http://docs.python.org/tutorial/controlflow.html#more-on-defining-functions</a></li>
</ul>
</div>
<div class="section" id="returning-values">
<h2><a class="toc-backref" href="#id21">Returning values</a></h2>
<ul>
<li><p class="first">Functions can use <span class="code">return</span> statement to return values that can be
assigned to variables or passed to other functions:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">multiply_by_two</span><span class="p">(</span><span class="n">number</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">return</span> <span class="n">number</span> <span class="o">*</span> <span class="mi">2</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">multiply_by_two</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span>
<span class="go">20</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">multiply_by_two</span><span class="p">(</span><span class="n">multiply_by_two</span><span class="p">(</span><span class="mi">2</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span>
<span class="go">8</span>
</pre></div>
</li>
<li><p class="first">Robot Framework keywords can also return values that can be assigned
to variables and then used as arguments to other keywords.</p>
</li>
</ul>
</div>
<div class="section" id="documenting-functions">
<h2><a class="toc-backref" href="#id22">Documenting functions</a></h2>
<ul>
<li><p class="first">In Python functions, as well as classes and modules, are documented with
so called doc strings:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">hello</span><span class="p">():</span>
<span class="gp">... </span>    <span class="sd">&quot;&quot;&quot;Prints &#39;Hello, world!&#39; to the standard output.&quot;&quot;&quot;</span>
<span class="gp">... </span>    <span class="k">print</span> <span class="s">&quot;Hello, world!&quot;</span>
<span class="gp">...</span>
</pre></div>
</li>
<li><p class="first">Interestingly the documentation is available dynamically:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">hello</span><span class="o">.</span><span class="n">__doc__</span>
<span class="go">Prints &#39;Hello, world!&#39; to the standard output.</span>
</pre></div>
</li>
<li><p class="first">Doc strings are covered pretty well in Dive Into Python:
<a class="reference external" href="http://diveintopython.net/getting_to_know_python/documenting_functions.html">http://diveintopython.net/getting_to_know_python/documenting_functions.html</a></p>
</li>
<li><p class="first">Robot Framework has <a class="reference external" href="http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool">libdoc.py</a> tool that can generate test library
documentation based on these doc strings. Documenting functions that
are used as keywords is thus very important.</p>
</li>
</ul>
</div>
</div>
<div class="section" id="container-data-types">
<h1><a class="toc-backref" href="#id23">Container data types</a></h1>
<ul class="simple">
<li>Python has a nice set of container data types built into the
language with a really simple syntax similarly as in Perl and
Ruby. You are going to use them a lot!</li>
<li>See Dive Into Python for more information and examples than shown
below: <a class="reference external" href="http://diveintopython.net/native_data_types">http://diveintopython.net/native_data_types</a></li>
</ul>
<div class="section" id="lists">
<h2><a class="toc-backref" href="#id24">Lists</a></h2>
<ul>
<li><p class="first">A list is an ordered collection of items which you normally access
by index.</p>
</li>
<li><p class="first">They also have handy methods like <span class="code">append</span>, <span class="code">insert</span> and
<span class="code">pop</span> to access or alter the list.</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;Some&#39;</span><span class="p">,</span> <span class="s">&#39;strings&#39;</span><span class="p">,</span> <span class="s">&#39;here&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">&#39;Some&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
<span class="go">&#39;strings&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="go">&#39;here&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">x</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">[&#39;Some&#39;, &#39;strings&#39;, &#39;HERE&#39;, 42]</span>
</pre></div>
</li>
</ul>
</div>
<div class="section" id="tuples">
<h2><a class="toc-backref" href="#id25">Tuples</a></h2>
<ul>
<li><p class="first">A tuple is a list like structure which you cannot alter after creating it.</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s">&#39;x&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="go">&#39;x&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;new value&#39;</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n-Identifier">&lt;module&gt;</span>
<span class="nc">TypeError</span>: <span class="n-Identifier">&#39;tuple&#39; object does not support item assignment</span>
</pre></div>
</li>
<li><p class="first">Notice that you must use a trailing comma to create a tuple with one
element:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">empty</span> <span class="o">=</span> <span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">one</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">two</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
</li>
</ul>
</div>
<div class="section" id="dictionaries">
<h2><a class="toc-backref" href="#id26">Dictionaries</a></h2>
<ul>
<li><p class="first">A dictionary is an unordered collection of key-value pairs. The same
data structure is often called hashmap.</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;x&#39;</span><span class="p">:</span> <span class="s">&#39;some value&#39;</span><span class="p">,</span> <span class="s">&#39;a&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">]</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="p">[</span><span class="s">&#39;x&#39;</span><span class="p">]</span>
<span class="go">&#39;some value&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&#39;b&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="p">[</span><span class="s">&#39;tuple&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">t</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span>
<span class="go">{&#39;a&#39;: 2, &#39;x&#39;: &#39;some value&#39;, &#39;b&#39;: 2, &#39;tuple&#39;: (1, 2, &#39;x&#39;)}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="s">&#39;x&#39;</span> <span class="ow">in</span> <span class="n">d</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="s">&#39;z&#39;</span> <span class="ow">in</span> <span class="n">d</span>
<span class="go">False</span>
</pre></div>
</li>
</ul>
</div>
</div>
<div class="section" id="control-flow">
<h1><a class="toc-backref" href="#id27">Control Flow</a></h1>
<div class="section" id="conditional-execution">
<h2><a class="toc-backref" href="#id28">Conditional execution</a></h2>
<ul>
<li><p class="first">Python has similar <span class="code">if/elif/else</span> structure as most other
programming languages.</p>
</li>
<li><p class="first">Notice that no parentheses are needed around the expression as in
Java or C.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">is_positive</span><span class="p">(</span><span class="n">number</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">number</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
        <span class="k">return</span> <span class="bp">True</span>
    <span class="k">return</span> <span class="bp">False</span>

<span class="k">def</span> <span class="nf">greet</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">time</span><span class="p">):</span>
    <span class="k">if</span> <span class="mi">7</span> <span class="o">&lt;</span> <span class="n">time</span> <span class="o">&lt;</span> <span class="mi">12</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;Good morning </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">name</span>
    <span class="k">elif</span> <span class="n">time</span> <span class="o">&lt;</span> <span class="mi">18</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;Good afternoon </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">name</span>
    <span class="k">elif</span> <span class="n">time</span> <span class="o">&lt;</span> <span class="mi">23</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;Good night </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">name</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s">, you should be sleeping!&#39;</span> <span class="o">%</span> <span class="n">name</span>
</pre></div>
</li>
</ul>
</div>
<div class="section" id="looping">
<h2><a class="toc-backref" href="#id29">Looping</a></h2>
<ul>
<li><p class="first"><span class="code">for</span> loops allow iterating over a sequence of items such as
a list. This is probably the loop you are going to use most often.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">greet_many</span><span class="p">(</span><span class="n">names</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">names</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">&#39;Hello </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">name</span>

<span class="k">def</span> <span class="nf">count_up</span><span class="p">(</span><span class="n">limit</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">limit</span><span class="o">+</span><span class="mi">1</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">num</span> <span class="o">==</span> <span class="n">limit</span><span class="p">:</span>
            <span class="k">print</span> <span class="s">&#39;bye!&#39;</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">print</span> <span class="n">num</span>
</pre></div>
</li>
<li><p class="first"><span class="code">while</span> loops iterate as long as given expression is true. Very handy
when waiting some event to occur.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">wait_until_message_received</span><span class="p">():</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="n">try_to_receive_message</span><span class="p">()</span>
    <span class="k">while</span> <span class="n">msg</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
        <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
        <span class="n">msg</span> <span class="o">=</span> <span class="n">try_to_receive_message</span><span class="p">()</span>
    <span class="k">return</span> <span class="n">msg</span>
</pre></div>
</li>
<li><p class="first">Both <span class="code">for</span> and <span class="code">while</span> loops have typical
<span class="code">continue</span> and <span class="code">break</span> statements that can be used to
end the current iteration or exit the loop altogether.</p>
</li>
<li><p class="first">For more examples and information see:</p>
<ul class="simple">
<li>Python Tutorial: <a class="reference external" href="http://docs.python.org/tutorial/controlflow.html">http://docs.python.org/tutorial/controlflow.html</a></li>
<li>Dive Into Python: <a class="reference external" href="http://diveintopython.net/file_handling/for_loops.html">http://diveintopython.net/file_handling/for_loops.html</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="list-comprehensions">
<h2><a class="toc-backref" href="#id30">List comprehensions</a></h2>
<ul>
<li><p class="first">Quite often <span class="code">for</span> loops can be replaced with even more concise list
comprehensions or generator expressions:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">numbers</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="o">-</span><span class="mi">5</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="o">-</span><span class="mi">32</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">42</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">positive</span> <span class="o">=</span> <span class="p">[</span> <span class="n">num</span> <span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="n">numbers</span> <span class="k">if</span> <span class="n">num</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">positive</span>
<span class="go">[1, 4, 42]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">sum</span><span class="p">(</span><span class="n">num</span> <span class="o">*</span> <span class="mi">2</span> <span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="n">positive</span><span class="p">)</span>
<span class="go">94</span>
</pre></div>
</li>
<li><p class="first">This syntax might look a bit strange at first but you will love it
very soon. To learn more see, for example, Dive Into Python:
<a class="reference external" href="http://diveintopython.net/native_data_types/mapping_lists.html">http://diveintopython.net/native_data_types/mapping_lists.html</a></p>
</li>
</ul>
</div>
</div>
<div class="section" id="modules">
<h1><a class="toc-backref" href="#id31">Modules</a></h1>
<div class="section" id="importing-modules">
<h2><a class="toc-backref" href="#id32">Importing modules</a></h2>
<ul class="simple">
<li>Importing existing Python modules is as simply as saying <span class="code">import
modulename</span>.</li>
<li>An alternative syntax is <span class="code">from modulename import something</span>.</li>
<li>Python has a comprehensive <a class="reference external" href="http://docs.python.org/lib/lib.html">standard library</a> and a <a class="reference external" href="http://pypi.python.org">package
index</a> with external modules so there is plenty of existing code to
be imported. It is recommended to study what is available to avoid
reinventing wheels.</li>
</ul>
</div>
<div class="section" id="creating-modules">
<h2><a class="toc-backref" href="#id33">Creating modules</a></h2>
<ul>
<li><p class="first">Because every <span class="path">.py</span> file is effectively a Python module, you
have already created at least <span class="code">hello</span> module.</p>
</li>
<li><p class="first">For example if we have the following code in a file called
<span class="path">example.py</span>:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;World&quot;</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;Hello, </span><span class="si">%s</span><span class="s">!&quot;</span> <span class="o">%</span> <span class="n">name</span>

<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&quot;__main__&quot;</span><span class="p">:</span>
    <span class="n">hello</span><span class="p">()</span>
</pre></div>
<p>then we can use it in the interpreter (or from other modules) like:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">example</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">example</span><span class="o">.</span><span class="n">hello</span><span class="p">(</span><span class="s">&quot;Tellus&quot;</span><span class="p">)</span>
<span class="go">Hello, Tellus!</span>
</pre></div>
</li>
<li><p class="first"><span class="code">if __name__ == &quot;__main__&quot;</span> block in the previous example is
important because it allows executing the file also as a script like
<span class="cli">python example.py</span>.</p>
</li>
<li><p class="first">The automatic <span class="code">__name__</span> attribute (Python has many of these
as you will see if you study it more) gets value <span class="code">&quot;__main___&quot;</span>
when the file is run as a script and the <span class="code">if</span> block is thus
executed only in that case.</p>
</li>
<li><p class="first">Bigger modules can be organized into several files inside a higher
level module as submodules. In this case the higher level module is
a directory with a special <span class="path">___init___.py</span> file.</p>
</li>
<li><p class="first">For more information about modules see Python Tutorial:
<a class="reference external" href="http://docs.python.org/tutorial/modules.html">http://docs.python.org/tutorial/modules.html</a></p>
</li>
</ul>
</div>
<div class="section" id="module-search-path-pythonpath">
<h2><a class="toc-backref" href="#id34">Module search path (PYTHONPATH)</a></h2>
<ul class="simple">
<li>Python modules are not automatically searched everywhere on you
machine. Python has certain default places to search modules for
(e.g. its own library directory which is often in place like
<span class="path">C:\Python26\Lib</span> or <span class="path">/usr/lib/python2.6</span>) and
additionally it looks for them from so called <span class="var">PYTHONPATH</span>.</li>
<li><span class="var">PYTHONPATH</span> is most often controlled using an environment
variable with the same name that contains places (mainly
directories) to look for Python modules. It is similar to Java's
<span class="var">CLASSPATH</span> and also to <span class="var">PATH</span> environment variable which
is used by an operating system to look for executable programs.</li>
<li><span class="var">PYTHONPATH</span> is important also with Robot Framework because it
can import test libraries only if the module containing the library
can be imported.</li>
</ul>
</div>
</div>
<div class="section" id="advanced-features">
<h1><a class="toc-backref" href="#id35">Advanced features</a></h1>
<div class="section" id="classes-and-instances">
<h2><a class="toc-backref" href="#id36">Classes and instances</a></h2>
<ul>
<li><p class="first">Python is an object-oriented language but as we have seen you do not
need to use classes everywhere like you need to with Java. It is
totally fine to just have a module with functions if that suites
your needs, but object oriented features are often really handy.</p>
</li>
<li><p class="first">The syntax for creating classes and then instances from them is
relatively straightforward:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyClass</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="s">&quot;World&quot;</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">print</span> <span class="s">&quot;</span><span class="si">%s</span><span class="s"> says hello to </span><span class="si">%s</span><span class="s">.&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_name</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">MyClass</span><span class="p">(</span><span class="s">&#39;Robot&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">hello</span><span class="p">()</span>
<span class="go">Robot says hello to World.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">hello</span><span class="p">(</span><span class="s">&#39;Tellus&#39;</span><span class="p">)</span>
<span class="go">Robot says hello to Tellus.</span>
</pre></div>
</li>
<li><p class="first">The only surprising part in the syntax is that every class method
must have <span class="code">self</span> as the first argument in the signature. After
you create an instance of the class Python binds the method, and it
also takes care of passing the <span class="code">self</span> argument automatically
so you do not use it when calling the method.</p>
</li>
<li><p class="first">To learn more about classes you can follow an interesting example
from Dive Into Python and/or study detailed information from Python
Tutorial:</p>
<ul class="simple">
<li><a class="reference external" href="http://diveintopython.net/object_oriented_framework">http://diveintopython.net/object_oriented_framework</a></li>
<li><a class="reference external" href="http://docs.python.org/tutorial/classes.html">http://docs.python.org/tutorial/classes.html</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="exceptions">
<h2><a class="toc-backref" href="#id37">Exceptions</a></h2>
<ul>
<li><p class="first">Python has an exception system similar to many other languages.
Exceptions are classes and the normal way to raise them is
<span class="code">raise SomeException(&quot;Error message&quot;)</span>.</p>
</li>
<li><p class="first">Exceptions are handled in a <span class="code">try/except</span> block:</p>
<div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
    <span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">IOError</span><span class="p">,</span> <span class="n">err</span><span class="p">:</span>
    <span class="k">print</span> <span class="s">&quot;Opening file </span><span class="si">%s</span><span class="s"> for reading failed: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">err</span><span class="p">)</span>
</pre></div>
</li>
<li><p class="first">The <span class="code">try/except</span> block can have multiple <span class="code">except</span>
branches, an optional <span class="code">else</span> to execute if no exception
occurred, and <span class="code">finally</span> to execute both when an exception
occurred and when it did not.</p>
</li>
<li><p class="first">Compared to Java there are some terminology differences
(<span class="code">raise</span> vs. <span class="code">throw</span> and <span class="code">except</span>
vs. <span class="code">catch</span>) but the biggest real difference is that there are
no checked exceptions. This means that you do not need to add
<span class="code">throws SomeException</span> to methods that may raise an exception.</p>
</li>
<li><p class="first">More information can be found, for example, from Dive Into Python:
<a class="reference external" href="http://diveintopython.net/file_handling/index.html">http://diveintopython.net/file_handling/index.html</a></p>
</li>
<li><p class="first">Exceptions are an important part of the Robot Framework Library API
because keywords use them to communicate failures to the framework.</p>
</li>
</ul>
</div>
<div class="section" id="regular-expressions">
<h2><a class="toc-backref" href="#id38">Regular expressions</a></h2>
<ul class="simple">
<li>Regular expressions are really handy for processing strings which is
a really common need in test automation.</li>
<li>Python has a really fast regular expression engine and it uses a
syntax derived from Perl's regexp syntax similarly as Java and many
other languages.</li>
<li>Dive Into Python contains a good introduction again:
<a class="reference external" href="http://diveintopython.net/regular_expressions/index.html">http://diveintopython.net/regular_expressions/index.html</a></li>
<li>Notice that Python strings also have many useful methods
(e.g. <span class="code">startswith</span>, <span class="code">find</span>, <span class="code">isdigit</span>) so regexps
are not needed as often as in Perl or Ruby.</li>
</ul>
</div>
</div>
<div class="section" id="unit-testing">
<h1><a class="toc-backref" href="#id39">Unit testing</a></h1>
<ul class="simple">
<li>Unit testing is important especially when you start having more
code and unit testing your test library code can be a really good
idea.</li>
<li>Python has several unit testing frameworks. Two of them,
<span class="code">unittest</span> and <span class="code">doctest</span>, are in the standard
library. The former is immediately familiar for anyone who has used
JUnit or some other xUnit framework and the other is interesting
because it allows using function doc strings for tests.</li>
<li>Dive Into Python has really good chapters about <a class="reference external" href="http://diveintopython.net/unit_testing/index.html">unit testing</a>,
<a class="reference external" href="http://diveintopython.net/unit_testing/stage_1.html">test-driven development</a> (TDD), and <a class="reference external" href="http://diveintopython.net/refactoring/index.html">refactoring</a>.</li>
</ul>
</div>
<div class="section" id="writing-test-libraries">
<h1><a class="toc-backref" href="#id40">Writing test libraries</a></h1>
<p>Robot Framework's test library API is really simple. It is explained
fully in <a class="reference external" href="http://code.google.com/p/robotframework/wiki/UserGuide">Robot Framework User Guide</a> and this tutorial only covers
the very basic features with an executable example.</p>
<div class="section" id="library-api-basics">
<h2><a class="toc-backref" href="#id41">Library API basics</a></h2>
<p>The test library can be either a module or a class.  In case of a
module, a keyword will be created for each top-level function in the
module. In case of a class, a keyword will be created for each public
method of the class.</p>
<p>The most important ways keywords can interact with the framework have already
been covered in this tutorial:</p>
<ul class="simple">
<li>Keyword name maps to the function name (case insensitively and
underscores removed).</li>
<li>Keywords have same arguments as implementing functions.</li>
<li>Failures are reported by raising exceptions.</li>
<li><span class="code">print</span> statement can be used to log messages.</li>
<li>Values can be returned using the <span class="code">return</span> statement.</li>
<li>Doc strings are used to document keywords.</li>
</ul>
</div>
<div class="section" id="executable-example">
<h2><a class="toc-backref" href="#id42">Executable example</a></h2>
<p>The example library and associated test data shown below demonstrate
the most important features of the test library API. You can execute
these test cases in your own environment and edit them to test also
other features. A precondition is having Robot Framework <a class="reference external" href="http://code.google.com/p/robotframework/wiki/Installation">installed</a>,
but then you only need to get <a class="reference external" href="ExampleLibrary.py">the library</a> and <a class="reference external" href="example_tests.tsv">the data</a>, and
run command <span class="cli">pybot example_tests.tsv</span>.</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">simple_keyword</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;Log a message&quot;&quot;&quot;</span>
    <span class="k">print</span> <span class="s">&#39;You have used the simplest keyword.&#39;</span>

<span class="k">def</span> <span class="nf">greet</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Logs a friendly greeting to person given as argument&quot;&quot;&quot;</span>
    <span class="k">print</span> <span class="s">&#39;Hello </span><span class="si">%s</span><span class="s">!&#39;</span> <span class="o">%</span> <span class="n">name</span>

<span class="k">def</span> <span class="nf">multiply_by_two</span><span class="p">(</span><span class="n">number</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Returns the given number multiplied by two</span>
<span class="sd">    </span>
<span class="sd">    The result is always a floating point number.</span>
<span class="sd">    This keyword fails if the given `number` cannot be converted to number.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="nb">float</span><span class="p">(</span><span class="n">number</span><span class="p">)</span> <span class="o">*</span> <span class="mi">2</span>

<span class="k">def</span> <span class="nf">numbers_should_be_equal</span><span class="p">(</span><span class="n">first</span><span class="p">,</span> <span class="n">second</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&#39;*DEBUG* Got arguments </span><span class="si">%s</span><span class="s"> and </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">first</span><span class="p">,</span> <span class="n">second</span><span class="p">)</span>
    <span class="k">if</span> <span class="nb">float</span><span class="p">(</span><span class="n">first</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">float</span><span class="p">(</span><span class="n">second</span><span class="p">):</span>
        <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s">&#39;Given numbers are unequal!&#39;</span><span class="p">)</span>
</pre></div>
<table border="1" class="tsv-example docutils">
<caption>Simple test cases using keywords from ExampleLibrary</caption>
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr><td><strong>*Settings*</strong></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Library</td>
<td>ExampleLibrary</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td><strong>*Test Cases*</strong></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Simple Test</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Simple Keyword</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Greet</td>
<td>Robot Framework</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Greet</td>
<td>World</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Returning Value</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>${result} =</td>
<td>Multiply By Two</td>
<td>4.1</td>
</tr>
<tr><td>&nbsp;</td>
<td>Numbers Should Be Equal</td>
<td>${result}</td>
<td>8.2</td>
</tr>
<tr><td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>Failing Test</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>&nbsp;</td>
<td>Numbers Should Be Equal</td>
<td>2</td>
<td>2</td>
</tr>
<tr><td>&nbsp;</td>
<td>Numbers Should Be Equal</td>
<td>2</td>
<td>3</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<p>Generated by <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>. Syntax highlighting by <a class="reference external" href="http://pygments.org/">Pygments</a>.</p>
<p>Generated on: 2012-03-10 09:43 UTC.
</p>

</div>
</body>
</html>
